home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / mus / edit / med_3_22.lha / programmers / modplayer / modplayer.doc < prev    next >
Text File  |  1992-01-01  |  9KB  |  239 lines
  1.     Instructions for using "modplayer.a", the stand-alone playroutine.
  2. ==========================================================================
  3.  
  4. "modplayer" is a piece of code (about 3 - 5 KBytes, depending on your needs)
  5. which is linked with your program and plays modules made in MED.
  6.  
  7. "modplayer" contains the following routines:
  8.     InitPlayer
  9.     RemPlayer
  10.     PlayModule
  11.     ContModule
  12.     StopPlayer
  13.     SetTempo
  14.  
  15. The arguments are passed in registers, and return values are returned in d0.
  16. These routines will trash registers d0-d1 and a0-a1.
  17.  
  18. And now the descriptions of each one:
  19. --------------------------------------------------------------------------
  20. InitPlayer -- initialize everything
  21.  
  22. Before you can call the other functions, you must call this function.
  23. It allocates the audio channels, timer, serial port (if MIDI) etc...
  24.  
  25. ARGUMENTS:    none
  26.  
  27. RETURNS:    0 if everything is ok, otherwise something failed.
  28.         If something failed, you can still call the other
  29.         routines - they just don't do anything.
  30. --------------------------------------------------------------------------
  31. RemPlayer -- return everything back
  32.  
  33. Call this when your program exits. It frees the audio channels etc. etc.
  34.  
  35. ARGUMENTS:    none
  36.  
  37. RETURNS:    nothing
  38. --------------------------------------------------------------------------
  39. PlayModule -- start playing a module
  40.  
  41. When you want to start playing call this.
  42.  
  43. ARGUMENTS:    a0 = pointer to the module. Where to get that pointer?
  44.         Don't panic, it's explained later....
  45.  
  46. RETURNS:    nothing
  47. --------------------------------------------------------------------------
  48. StopPlayer -- stop playing
  49.  
  50. ARGUMENTS:    no arguments
  51.  
  52. RETURNS:    nothing
  53. --------------------------------------------------------------------------
  54. ContModule -- continue playing
  55.  
  56. This routine continues playing the module from the point it was stopped.
  57.  
  58. ARGUMENTS:    a0 = pointer to the module
  59.  
  60. RETURNS:    nothing
  61. --------------------------------------------------------------------------
  62. SetTempo -- set the playback tempo
  63.  
  64. ARGUMENTS:    d0 = new tempo (1 - 240)
  65.  
  66. RETURNS:    nothing
  67. --------------------------------------------------------------------------
  68.  
  69. "modplayer.a" is the source code of the music routine. It contains stuff
  70. that may be unnecessary for your purposes, and just takes time and memory.
  71. There are some "switches" at the beginning of the source, that allow you
  72. to turn off features you don't need. They are:
  73.  
  74. MIDI        If only the Amiga audio channels are used, set this to 0.
  75. AUDDEV        For some purposes, you may want to disable the code that
  76.         allocates the audio channels using "audio.device", e.g.
  77.         in a non-multitasking environment. Normally this should
  78.         be 1.
  79. SYNTH        If synth/hybrid sounds are not in use, this can be set to
  80.         zero.
  81. CHECK        This does some checkings to ensure that several values are
  82.         correct (e.g. is the sample in memory, no Amiga effects on
  83.         MIDI-tracks etc..). If you know that the song is correct,
  84.         you can safely turn the checks off.
  85. RELVOL        If you don't need the "relative volume", this can be zero.
  86. IFF53        If the song doesn't contain IFF 3- or 5-octave samples,
  87.         this can be zero.
  88. HOLD        This turns off the hold/decay features.
  89.  
  90.  
  91. There's an additional flag, EASY. If set, the usage of the player routines
  92. is even more simplified, and you enter the module name into an INCBIN
  93. statement. Then there are two routines (_startmusic, _endmusic) you call
  94. to start and stop the music (the music can be started ONLY ONCE). The
  95. EASY option is suitable for demos etc. where only a single tune is
  96. required. This option also replaces the 'easyplayer.a' from the previous
  97. release of OctaMED and MED.
  98.  
  99. "modplayer.a" also supports multi-modules. It defines a UWORD modnum
  100. (in assembler: _modnum). Set this variable to the number of the song
  101. you want to play before calling PlayModule (0 is the first, 1 is the
  102. second song etc..). For example:
  103.     #include "modplayer.h" /* defines 'modnum' */
  104.     ...
  105.     modnum = 1; /* Play the second module */
  106.     PlayModule(module);
  107.     ...
  108. Assembler:
  109.     xref    _modnum
  110.     xref    _PlayModule
  111.     ...
  112.     move.w    #1,_modnum
  113.     lea    _module,a0
  114.     jsr    _PlayModule(pc)
  115.     ...
  116.  
  117. Timing
  118. ======
  119. If you need vertical blanking timing, you can set VBLANK to 1 and CIAB to 0.
  120. In normal use this is not recommended (because of the 16 % difference in
  121. playing speed with NTSC and PAL Amigas), but if tight synchronization to
  122. vertical blanking (e.g. in most demos/games) is required, VBLANK should be
  123. used.
  124.  
  125. Assembling
  126. ==========
  127. "modplayer.a" can be assembled by using A68k V2.61 (or later) or HiSoft
  128. Devpac 2 without need to make changes. Other assemblers may need some
  129. small changes to work correctly (mostly because the directives they support
  130. may be slightly different). The freely distributable assembler, A68k is
  131. available e.g. on Fish disk #314. If you're working on a linker environment
  132. (e.g. programming in C), you've to include the resulted "modplayer.o" in
  133. your .lnk-file.
  134.  
  135. ==========================================================================
  136.  
  137. And how to get some music?
  138.  
  139. You have two ways to get the music:
  140. 1. Include the module in your final executable.
  141. 2. Save the module as a separate disk file and load it when needed
  142.    (this is probably the best way if you have more than one song, and
  143.     you don't want to use multi-modules).
  144.  
  145. First I cover the first method:
  146. --------------------------------------------------------------------------
  147. Including the module in your final executable:
  148.  
  149. The direct object file saving is removed now (you can still use the previous
  150. versions which support it, if you want). There's now another way to convert
  151. the song to an object file.
  152.  
  153. There's a new utility, Objconv, which loads the module and dumps it into an
  154. object file. Here's an example how to use it:
  155.  
  156. - Save the song as a module (MED module!).
  157. - Use Objconv e.g. objconv medmodule mod.o
  158. - Objconv requests the symbol name, enter "song" (without "'s), for example.
  159. - Now there's a file 'mod.o'. Link this file, and the file 'reloc.o'
  160.   with your program.
  161. - In your program, you define the module:
  162.     #include "modplayer.h"
  163.     ...
  164.     extern struct MMD0 far song;
  165.   You must relocate the module before it's used. Do this only once!
  166.   This is done by
  167.     RelocModule(&song);
  168.   RelocModule expects the argument in stack, so use __stdargs, if you've
  169.   turned registerized arguments on.
  170.  
  171. In assembler, you'd do exactly in the same way, except:
  172.     xref    _song
  173.     xref    _RelocModule
  174.     xref    _PlayModule
  175.  
  176.     ... (assuming all init stuff is here)
  177.  
  178.     lea    _song,a0
  179.     move.l    a0,-(sp)    ;push into stack
  180.     jsr    _RelocModule(pc)
  181.     lea    _song,a0    ;this is passed in register a0
  182.     jsr    _PlayModule
  183.     ...
  184.  
  185. Note: if you've got an assembler that supports 'incbin' directive or
  186. equivalent, you can use it instead of the Objconv. Relocation is required
  187. in any case.
  188.  
  189. And the second method (loading modules from disk):
  190. --------------------------------------------------------------------------
  191. File "loadmod.a" contains three routines:
  192.     LoadModule
  193.     UnLoadModule
  194.     RelocModule (not external)
  195.  
  196. You usually need only the first two of them. RelocModule is used by
  197. LoadModule.
  198.  
  199. --------------------------------------------------------------------------
  200. LoadModule -- loads a module from disk
  201.  
  202. This function loads a module from disk. Note that relocation is done
  203. automatically, so you must not RelocModule() a module obtained by using
  204. this routine.
  205.  
  206. ARGUMENTS:    a0 = pointer to file name
  207.  
  208. RETURNS:    d0 = pointer to the module, if something failed: 0
  209. --------------------------------------------------------------------------
  210. UnLoadModule -- free the module from memory
  211.  
  212. Frees the module. Remember to StopPlayer() before you unload the module
  213. that is currently playing. Also remember to free all modules you've loaded
  214. before you exit the program.
  215.  
  216. ARGUMENTS:    a0 = pointer to the module (may be 0)
  217.  
  218. RETURNS:    nothing, nothing and nothing
  219. --------------------------------------------------------------------------
  220.  
  221. Just call LoadModule to load the module and send the returned pointer to
  222. PlayModule. Easy??
  223.  
  224. ==========================================================================
  225.  
  226. REMEMBER:    All functions expect the arguments in registers (except
  227.         RelocModule() from reloc.o). This is automatically (??)
  228.         handled by you when you program in assembler, but it is
  229.         not automatically handled when you're programming in C.
  230.  
  231. If you have Lattice/SAS C V5.xx, this is done automatically if you include
  232. "modplayer.h" in all your code modules which call modplayer. If you
  233. have a compiler which doesn't support argument passing in registers,
  234. then you have to write the stub routines in assembler.
  235.  
  236. That was it. See also the small example sources.
  237.  
  238. ==========================================================================
  239.